docs: sync from help-docs (source of truth) - #1083

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use level-two headings for the documentation cards.

Each card heading follows the page level-one heading. Level-three headings skip level two and create an invalid heading outline. Change all six card headings from ### to ##.

-### [Quickstart](/getting-started/)
+## [Quickstart](/getting-started/)

-### [Tools](/configure/tools/)
+## [Tools](/configure/tools/)

-### [Interfaces](/usage/tui/)
+## [Interfaces](/usage/tui/)

-### [Configure](/configure/)
+## [Configure](/configure/)

-### [Governance](/configure/governance/)
+## [Governance](/configure/governance/)

-### [Develop & Extend](/develop/sdk/)
+## [Develop & Extend](/develop/sdk/)

Also applies to: 41-41, 54-54, 67-67, 80-80, 93-93

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/docs/index.md` at line 28, Change the six documentation card headings,
including “Quickstart” and the headings at the referenced locations, from
level-three (`###`) to level-two (`##`) headings while preserving their existing
text and links.

Source: Linters/SAST tools

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

#!/bin/bash
set -euo pipefail

origin="${DOCS_ORIGIN:-https://docs.altimate.sh}"

for path in /quickstart/ /code/quickstart/; do
  printf '%s%s -> ' "$origin" "$path"
  curl -sS -o /dev/null -w '%{http_code}\n' -L "$origin$path"
done

Remove the outdated /code/ route set.

docs/mkdocs.yml#L4-L4 and docs/docs/index.md#L16-L16 use root-relative docs.altimate.sh paths. docs/docs/llms.txt still points every link under /code/, which does not resolve at the deployed docs origin. Update docs/docs/llms.txt to remove the /code/ prefix or regenerate it from the canonical routing policy.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/mkdocs.yml` at line 4, Update docs/docs/llms.txt entries to remove the
outdated /code/ prefix so every link matches the root-relative routing
established by site_url in docs/mkdocs.yml and docs/docs/index.md. Modify
docs/docs/llms.txt lines 4-42; docs/mkdocs.yml lines 4-4 and docs/docs/index.md
lines 16-16 require no direct changes and serve as routing references.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

#!/bin/bash
set -euo pipefail

echo "Configured Markdown extension:"
sed -n '57,68p' docs/mkdocs.yml

echo "Potential emoji shortcodes:"
rg -n ':[A-Za-z0-9_+-]+:' docs/docs || true

echo "Installed MkDocs and PyMdown dependency declarations:"
fd -HI '^(requirements.*\.(txt|in)|pyproject\.toml|poetry\.lock|uv\.lock)$' . \
  -x rg -n 'mkdocs|pymdown|material' {}

#!/bin/bash
set -euo pipefail

python3 - <<'PY'
try:
    import pymdownx.emoji
    import inspect
    settings = getattr(pymdownx.emoji, 'DEFAULT_SETTINGS', None)
    print('pymdownx.emoji available')
    print('DEFAULT_SETTINGS:', settings)
    for name in ('emoji_index', 'emoji_generator'):
        if settings:
            print(name, 'default type:', type(settings.get(name)).__name__, 'default:', repr(settings.get(name)))
except Exception as e:
    print('pymdownx.emoji unavailable:', repr(e))

try:
    import pymdownx.emoji
    ext = pymdownx.emoji.EmojiExtension()
    config = {'emoji_index': None, 'emoji_generator': None}
    ret = ext.on_config(config) or config
    print('on_config returns', type(ret).__name__ if ret is not None else None)
    print('emoji_index after config:', type(ret.get('emoji_index')).__name__ if 'emoji_index' in ret else 'absent', repr(ret.get('emoji_index')))
    print('emoji_generator after config:', type(ret.get('emoji_generator')).__name__ if 'emoji_generator' in ret else 'absent', repr(ret.get('emoji_generator')))
except Exception as e:
    print('configuration test failed:', repr(type(e).__name__ + ': ' + str(e)))
PY

Restore the Material emoji generators before release.

emoji_index and emoji_generator are required callable settings for pymdownx.emoji when emoji shortcodes such as :material-cog:{ .lg .middle } are rendered. Setting them to null leaves no valid index or generator for those icons and can break MkDocs builds on pages that use Material emojis. Keep the original Material extensions or replace them with valid !!python/name:... callables.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/mkdocs.yml` around lines 66 - 68, Restore valid callable Material emoji
settings under pymdownx.emoji by replacing the null emoji_index and
emoji_generator values with the original Material extensions or equivalent
!!python/name callables. Ensure Material emoji shortcodes render successfully
during MkDocs builds.

WARNING: pymdownx.emoji index/generator dropped to null — breaks the Material icon shortcodes still used in the docs.

The sync replaced the required !!python/name:material.extensions.emoji.twemoji / to_svg tags with null. Those !!python/name: tags cannot survive a plain YAML parse/reserialize (a likely sync_to_oss.py artifact), but Material for MkDocs needs them to render the :octicons-*: / :material-*: shortcodes that are still present in the synced content (e.g. [:octicons-arrow-right-24: Browse more examples] in docs/docs/getting-started/index.md). With null, those shortcodes either render as literal text (silently — CI's mkdocs build may not catch it) or fail the build outright, depending on the pinned pymdownx version. Restore the tags:

  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

P2: The de-prefixing pass stripped the https://help.altimate.ai domain from these links but left the /code/ path segment in place, e.g. /code/quickstart/. Since the deployed site's routes (per mkdocs.yml nav) don't have a /code/ prefix, these llms.txt links won't resolve at the deployed docs origin.

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/llms.txt, line 10:

<comment>The de-prefixing pass stripped the `https://help.altimate.ai` domain from these links but left the `/code/` path segment in place, e.g. `/code/quickstart/`. Since the deployed site's routes (per mkdocs.yml nav) don't have a `/code/` prefix, these llms.txt links won't resolve at the deployed docs origin.</comment>

<file context>
@@ -1,42 +1,42 @@
-- [Quickstart (5 min)](https://help.altimate.ai/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes.
-- [Full Setup Guide](https://help.altimate.ai/code/getting-started/): Complete installation, warehouse configuration for all 8 supported warehouses, LLM provider setup, and first-run walkthrough.
-- [Network & Proxy](https://help.altimate.ai/code/reference/network/): Proxy configuration, CA certificate setup, firewall requirements.
+- [Quickstart (5 min)](/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes.
+- [Full Setup Guide](/code/getting-started/): Complete installation, warehouse configuration for all 8 supported warehouses, LLM provider setup, and first-run walkthrough.
+- [Network & Proxy](/code/reference/network/): Proxy configuration, CA certificate setup, firewall requirements.
</file context>

P3: These new card headings jump from the page's h1 straight to h3, skipping h2, which creates an invalid heading outline (flagged by markdownlint MD001). Change ### [Quickstart](/getting-started/) and the other five card headings to ##.

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/index.md, line 28:

<comment>These new card headings jump from the page's h1 straight to h3, skipping h2, which creates an invalid heading outline (flagged by markdownlint MD001). Change `### [Quickstart](/getting-started/)` and the other five card headings to `##`.</comment>

<file context>
@@ -1,10 +1,107 @@
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 3 14h7l-1 8 10-12h-7l1-8z"/></svg>
+</div>
+
+### [Quickstart](/getting-started/)
+
+Install, connect a warehouse and an LLM, and make your first run in under five minutes.
</file context>

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use level-two headings for documentation card headings.

Both pages use ### for cards without a level-two parent. This creates an invalid heading outline. Change the affected card headings to ##.

• docs/docs/getting-started/index.md#L54-L54: change the six card headings at Lines 54, 67, 80, 93, 106, and 119.
• docs/docs/index.md#L28-L28: change the six card headings at Lines 28, 41, 54, 67, 80, and 93.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/docs/getting-started/index.md` at line 54, Change all documentation card
headings from level-three to level-two headings: update the six card headings at
docs/docs/getting-started/index.md lines 54, 67, 80, 93, 106, and 119, and the
six card headings at docs/docs/index.md lines 28, 41, 54, 67, 80, and 93.

Source: Linters/SAST tools

CRITICAL — mkdocs build fails outright; the docs deploy is broken

The YAML round-trip replaced the !!python/name: tags with null, and pymdownx.emoji calls inspect.getfullargspec() on emoji_index. Building this branch aborts:

ERROR - Config value 'markdown_extensions': Failed to load extension 'pymdownx.emoji'.
  File ".../pymdownx/emoji.py", line 257, in _set_index
    if len(inspect.getfullargspec(index).args):
TypeError: unsupported callable
Aborted with a configuration error!

main builds clean (exit 0); this branch does not. .github/workflows/docs.yml runs exactly mkdocs build -f docs/mkdocs.yml -d site, so the Pages job fails and nothing publishes. GitHub Pages keeps serving the last successful build, so the site does not go dark — it silently freezes, and every future docs change fails to deploy with no user-visible signal.

The extension is genuinely in use: 17 :octicons-arrow-right-24: plus :material-github:, :material-palette:, :material-puzzle:.

Fix — restore the tags, and make the sync preserve unknown YAML tags (or patch only the nav: key instead of rewriting the whole file):

- pymdownx.emoji:
    emoji_index: !!python/name:material.extensions.emoji.twemoji
    emoji_generator: !!python/name:material.extensions.emoji.to_svg

Patching just these two lines makes the build succeed, which is how the remaining issues below were confirmed.

MAJOR — 36 nav entries point at files that don't exist

This entire Altimate MCP section was lifted from the unified help-docs nav, but the content was never copied: docs/docs/datamates/ does not exist in this repo. main has zero datamates/ nav entries.

With the emoji fix applied so the build can run, MkDocs emits 36 warnings:

WARNING - A reference to 'datamates/index.md' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING - A reference to 'datamates/user-guide/home.md' ...
... (36 total)

These are warnings, not build failures — strict is unset — so this ships rather than failing CI. Confirmed against the built artifact: the rendered index.html contains the Altimate MCP section with 37 datamates references emitted as raw unprocessed paths:

href="datamates/examples/examples.md"
href="datamates/faq/security.md"

So these publish as dead links pointing at .md files. Note this also becomes a hard build failure the moment anyone sets strict: true.

Fix — either sync the datamates/** content, or have the sync prune nav subtrees whose targets aren't in the mirrored file set and replace this section with a single external link to https://help.altimate.ai/datamates/.

MAJOR — root-relative cross-product links 404 on this domain

This repo deploys standalone: docs/docs/CNAME is docs.altimate.sh and site_url: https://docs.altimate.sh. The unified-site "de-prefixing" rewrote working fully-qualified URLs into root-relative paths that only resolve on help.altimate.ai.

git grep confirms 0 such links on main, 8 on this branch. On docs.altimate.sh, /datamates/, /dbt-power-user/, and /snowflake-native-app/ are all 404s — and /datamates/ is unreachable in this repo regardless, since that content was never synced.

Fix — keep cross-product links fully qualified (https://help.altimate.ai/...). De-prefixing is only correct for pages that exist within this mirror.

All three targets here are external products, so all three should be absolute URLs.

MAJOR — de-prefixed link now 404s on docs.altimate.sh

This is the clearest instance of the regression — a working fully-qualified URL was rewritten into a path that only resolves on help.altimate.ai:

--- **[Altimate LLM Gateway](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/)** — ...
-+- **[Altimate LLM Gateway](/datamates/user-guide/components/llm-gateway/)** — ...

This repo publishes to docs.altimate.sh (CNAME + site_url), where /datamates/... does not exist. The LLM Gateway link is the most damaging of the eight, since it appears in provider setup, quickstart, and IDE guidance.

Fix — restore the fully-qualified https://help.altimate.ai/datamates/user-guide/components/llm-gateway/.

MAJOR — de-prefixed link now 404s on docs.altimate.sh

This is the clearest instance of the regression — a working fully-qualified URL was rewritten into a path that only resolves on help.altimate.ai:

--- **[Altimate LLM Gateway](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/)** — ...
-+- **[Altimate LLM Gateway](/datamates/user-guide/components/llm-gateway/)** — ...

This repo publishes to docs.altimate.sh (CNAME + site_url), where /datamates/... does not exist. The LLM Gateway link is the most damaging of the eight, since it appears in provider setup, quickstart, and IDE guidance.

Fix — restore the fully-qualified https://help.altimate.ai/datamates/user-guide/components/llm-gateway/.

MAJOR — same CTA mis-target as the homepage

/getting-started/quickstart/ resolves to getting-started/quickstart.md — the page titled "Setup Guide", which this PR removes from the nav — not to the nav-labeled Quickstart (quickstart-new.md).

MINOR — same CTA mis-target in the footer links

[Quickstart](/getting-started/quickstart/) resolves to the "Setup Guide" page rather than the nav-labeled Quickstart (quickstart-new.md).

MINOR — this file was touched but left materially stale

Two routes were corrected here (both good — verified they now point at real pages), but the file still contradicts docs shipped in this same commit:

This is the file AI consumers read as the canonical product index, and it now disagrees with its own sibling pages.

Fix — regenerate from source data rather than hand-editing individual URLs.

MINOR — the homepage is the one page with no SEO description

Of the 73 changed markdown files, 72 received both title and description. This one — the new landing page and the highest-value SEO surface in the site — has title and hide but no description, so it falls back to the generic site-wide site_description.

Fix — add a description matching this page's actual pitch.

MINOR — brand rename is half-applied

The "Datamates" → "Altimate MCP" rename was applied to command-palette labels and headings but not body copy. This line reads:

The Datamates extension offers additional capabilities … See the [Altimate MCP documentation]

…under a heading that says "Full Altimate MCP Documentation" — three names for one thing in two sentences. Six "Datamates" references remain in this file (lines 3, 8, 20, 24, 28, 73) plus develop/ecosystem.md:22.

Fix — if the VS Code marketplace listing is still literally named "Datamates", state that once explicitly ("the Altimate MCP extension, listed as Datamates in the marketplace") rather than alternating between the two names.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

#!/bin/bash
# Description: Confirm the copy-page control has a script and markup source.
set -euo pipefail

# Find the mkdocs config and print its JS/CSS asset registration.
fd -t f 'mkdocs.yml' | while IFS= read -r cfg; do
  echo "=== $cfg ==="
  rg -n -A 8 'extra_javascript|extra_css|custom_dir' "$cfg"
done

# Find any source that produces the ak-copy-page markup or behaviour.
rg -n -C 3 'ak-copy-page' --glob '!**/*.css'

#!/bin/bash
set -euo pipefail

echo "=== tracked docs-related files ==="
git ls-files 'docs/**' | sed -n '1,200p'

echo "=== copy-page stylesheet ==="
if [ -f docs/docs/assets/stylesheets/copy-page.css ]; then
  cat -n docs/docs/assets/stylesheets/copy-page.css | sed -n '1,220p'
fi

echo "=== references to copy page classes/state (all tracked files) ==="
python3 - <<'PY'
import subprocess, re, pathlib
files = subprocess.check_output(["git","ls-files"], text=True).splitlines()
needle = re.compile(r'ak-copy-page|aria-expanded|copied|copy-page')
for f in files:
    try:
        text = pathlib.Path(f).read_text(encoding='utf-8', errors='replace')
    except Exception:
        continue
    if needle.search(text):
        print(f"--- {f} ---")
        lines = text.splitlines()
        for i,l in enumerate(lines,1):
            if needle.search(l):
                start=max(1,i-4); end=min(len(lines),i+4)
                for j in range(start,end+1):
                    print(f"{j}: {lines[j-1]}")
PY

echo "=== mkdocs js/custom_dir summary ==="
python3 - <<'PY'
import pathlib, re, subprocess
mkdocs = pathlib.Path('docs/mkdocs.yml')
if mkdocs.exists():
    txt = mkdocs.read_text()
    for section in ['custom_dir','extra_javascript','extra_css']:
        print(f"{section}: {section in txt}")
PY

Register the copy-page script with the same override context.

docs/mkdocs.yml currently only registers extra_css and custom_dir; this stylesheet adds aria-expanded, [hidden], and copied state styles for .ak-copy-page, so add the matching extra_javascript entry for the controller that injects or controls that markup.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/docs/assets/stylesheets/copy-page.css` around lines 4 - 13, Add the
copy-page controller to the existing MkDocs override configuration through an
extra_javascript entry, alongside the current extra_css and custom_dir settings.
Ensure it references the script responsible for controlling .ak-copy-page markup
and its aria-expanded, hidden, and copied states.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add visible focus styles for the copy control.

The stylesheet defines :hover and [aria-expanded='true'] states, but no focus state. Keyboard users get no reliable focus indicator on .ak-copy-page__main, .ak-copy-page__toggle, or the menu buttons. The menu is a disclosure widget, so keyboard operation is expected.

 .ak-copy-page__main:hover,
 .ak-copy-page__toggle:hover,
 .ak-copy-page__toggle[aria-expanded='true'] {
   background: var(--md-default-fg-color--lightest);
   border-color: var(--md-default-fg-color--lighter);
 }
+
+.ak-copy-page__main:focus-visible,
+.ak-copy-page__toggle:focus-visible,
+.ak-copy-page__menu button:focus-visible {
+  outline: 2px solid var(--md-accent-fg-color);
+  outline-offset: 2px;
+}

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/docs/assets/stylesheets/copy-page.css` around lines 41 - 46, Add visible
keyboard focus styles for the copy controls by extending the existing state rule
around .ak-copy-page__main and .ak-copy-page__toggle to include appropriate
focus selectors, including the menu buttons used by the disclosure widget.
Ensure focused controls have a reliable visual indicator without removing the
current hover or expanded-state styling.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Scope the .md-content__button rule; it currently hides the button on every page.

The comment states the intent is hub index pages. The selector has no scope, so it hides Material's content buttons site-wide. This removes the "Edit this page" and "View source" links from all documentation pages.

If the goal is hub indexes only, scope the rule to the homepage wrapper class that the rest of this file already uses.

-/* ---- Hide ToC button on hub indexes (we hide toc in frontmatter) -- */
-.md-content__button { display: none; }
+/* ---- Hide ToC button on hub indexes (we hide toc in frontmatter) -- */
+.ak-home .md-content__button { display: none; }

If the site-wide hide is intentional, update the comment to say so.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/docs/assets/stylesheets/extra.css` around lines 818 - 819, Scope the
.md-content__button rule to the existing homepage wrapper class used elsewhere
in the stylesheet, so the button is hidden only on hub index pages while
remaining visible on other documentation pages; keep the comment aligned with
that scoped behavior.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use the canonical LLM Gateway documentation URL.

This link targets the /datamates/ product namespace. Replace it with the standalone documentation origin used by this product.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/docs/getting-started/quickstart.md` around lines 38 - 39, Update the
Altimate LLM Gateway link in the quickstart tip to use the product’s canonical
standalone documentation URL instead of the `/datamates/` namespace, while
preserving the surrounding link text and description.